前端 WebHID 功能检测：掌握设备能力发现

WebHID API 为 Web 应用程序直接与各种人机接口设备 (HID) 交互开辟了激动人心的可能性。虽然基本通信很简单，但真正释放其潜力在于有效地检测设备功能。本文为使用 WebHID 进行功能检测提供了全面的指南，使您能够构建更丰富、响应更灵敏和定制化的 Web 体验。

什么是 WebHID 以及为何功能检测至关重要？

WebHID 是一个 Web API，它允许网站访问 HID 设备，这些设备包括从键盘、鼠标到游戏控制器、传感器和定制硬件的各种设备。与依赖标准化接口的传统 Web API 不同，WebHID 提供了对设备原始数据和控制机制的直接访问。

然而，挑战在于 HID 设备种类繁多。一个制造商的游戏手柄可能与另一个制造商的按钮、轴或传感器不同。一个定制的工业传感器可能有独特的数据格式或配置选项。如果没有一个强大的功能检测方法，您的 Web 应用程序将不得不依赖假设，从而导致兼容性问题、功能受限和糟糕的用户体验。

功能检测是以编程方式识别已连接 HID 设备的能力和功能的过程。这允许您的 Web 应用程序根据正在使用的特定设备动态调整其行为和用户界面。这确保了为每个用户提供最佳性能、兼容性和量身定制的体验。

理解 HID 报告和描述符

在深入研究代码之前，理解 HID 报告和描述符的基本概念至关重要。这些是定义设备如何与主机系统通信的关键元素。

HID 报告

一个 HID 报告是设备发送给主机或从主机接收的数据包。主要有三种类型的报告：

• 输入报告 (Input Reports): 数据从设备发送到主机（例如，按钮按下、传感器读数）。
• 输出报告 (Output Reports): 数据从主机发送到设备（例如，设置 LED 颜色、控制电机速度）。
• 功能报告 (Feature Reports): 用于查询和配置设备功能（例如，获取固件版本、设置灵敏度级别）。

HID 描述符

一个 HID 描述符是一个二进制结构，用于描述设备的功能，包括：

• 它支持的报告类型（输入、输出、功能）。
• 每种报告内数据的格式（例如，大小、数据类型、位字段）。
• 每个数据元素的含义（例如，按钮1、X轴、温度传感器）。

描述符本质上是一个蓝图，它告诉操作系统（以及您的 Web 应用程序）如何解释设备发送的数据。访问和解析此描述符是 WebHID 中功能检测的基础。

使用 WebHID 进行功能检测的方法

使用 WebHID 进行功能检测有几种方法，每种方法都有其优缺点：

1. 手动解析描述符：最直接但也是最复杂的方法。它涉及获取原始 HID 描述符，并根据 HID 规范手动解释其结构。
2. 使用 HID 报告 ID：许多设备使用报告 ID 来区分不同类型的报告。通过发送带有特定 ID 的功能报告请求，您可以确定设备是否支持该功能。
3. 供应商定义的用法页和用法：HID 设备可以定义自定义的用法页和用法来表示供应商特定的功能。查询这些值可以帮助您识别特定功能的存在。
4. 预定义功能集或数据库：根据供应商 ID、产品 ID 或其他标识符维护一个已知设备功能的数据库。这使得对常见设备的快速简便功能检测成为可能。

1. 手动解析描述符：深入探讨

手动解析描述符提供了对功能检测最精细的控制。它涉及以下步骤：

1. 请求设备访问：使用 navigator.hid.requestDevice() 提示用户选择一个 HID 设备。
2. 打开设备：调用 device.open() 建立连接。
3. 获取 HID 描述符：不幸的是，WebHID API 不直接暴露原始的 HID 描述符。这是一个重大的限制。一个常见的解决方法是通过 device.controlTransferIn() 发送一个“获取描述符”控制传输请求（如果设备支持）。然而，这并非普遍支持。因此，其他方法通常更可靠。
4. 解析描述符：一旦您获得了描述符（如果能获得的话！），您需要根据 HID 规范对其进行解析。这涉及解码二进制数据并提取有关报告类型、数据大小、用法和其他相关详细信息。

示例（仅为说明，因为直接描述符访问受限）：

此示例假设您有办法获取描述符，可能通过某种变通方法或外部库。这是棘手的部分。

asyn_c function getDeviceDescriptor(device) {
  // 挑战在于：如何获取描述符。
  // 在现实中，这部分通常被省略或用其他方法替代。
  // 此示例仅用于说明目的。
  //  考虑使用库或其他方法来获取描述符。
  
  // 模拟接收描述符（请替换为实际的获取代码）
  const descriptor = new Uint8Array([0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 0x15, 0x00, 0x25, 0x01, 0x95, 0x03, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75, 0x05, 0x81, 0x03, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x15, 0x81, 0x25, 0x7F, 0x75, 0x08, 0x95, 0x02, 0x81, 0x06, 0xC0, 0xC0]);
  return descriptor;
}

asyn_c function analyzeDescriptor(device) {
  const descriptor = await getDeviceDescriptor(device);

  // 这是一个简化的解析示例。真实的解析更为复杂。
  let offset = 0;

  while (offset < descriptor.length) {
    const byte = descriptor[offset];

    switch (byte) {
      case 0x05: // 用法页
        const usagePage = descriptor[offset + 1];
        console.log("Usage Page:", usagePage.toString(16));
        offset += 2;
        break;
      case 0x09: // 用法
        const usage = descriptor[offset + 1];
        console.log("Usage:", usage.toString(16));
        offset += 2;
        break;
      case 0xA1: // 集合
        const collectionType = descriptor[offset + 1];
        console.log("Collection Type:", collectionType.toString(16));
        offset += 2;
        break;
      // ... 其他项目类型的 case ...
      default:
        console.log("Unknown Item:", byte.toString(16));
        offset++;
    }
  }
}

挑战：

• 复杂性：解析 HID 描述符需要对 HID 规范有深入的了解。
• 有限的直接访问：WebHID 不直接提供 HID 描述符，这使得这种方法难以可靠地实现。
• 易于出错：由于描述符的复杂结构，手动解析很容易出错。

适用场景：

• 当您需要对功能检测进行最精细的控制，并愿意投入大量精力去理解 HID 规范时。
• 当其他方法不足以识别您需要的特定功能时。

2. 使用 HID 报告 ID：有针对性的功能查询

许多 HID 设备利用报告 ID 来区分不同类型的报告。通过发送带有特定 ID 的功能报告请求，您可以确定设备是否支持特定功能。此方法依赖于设备固件在功能存在时以特定值响应。

示例：

asyn_c function checkFeatureSupport(device, reportId, expectedResponse) {
  try {
    const data = new Uint8Array([reportId]); // 使用报告 ID 准备请求
    await device.sendFeatureReport(reportId, data);

    // 监听来自设备的输入报告以表明成功。
    device.addEventListener("inputreport", (event) => {
        const { data, reportId } = event;
        const value = data.getUint8(0);  // 假设是单字节响应

        if(value === expectedResponse){
            console.log(`Feature with Report ID ${reportId} is supported.`);
            return true;
        } else {
            console.log(`Feature with Report ID ${reportId} returned unexpected value.`);
            return false;
        }
    });

    
    // 或者，如果设备立即响应 getFeatureReport
    // const data = await device.receiveFeatureReport(reportId);
    // if (data[0] === expectedResponse) {
    //   console.log(`Feature with Report ID ${reportId} is supported.`);
    //   return true;
    // } else {
    //   console.log(`Feature with Report ID ${reportId} is not supported.`);
    //   return false;
    // }

  } catch (error) {
    console.error(`Error checking feature with Report ID ${reportId}:`, error);
    return false; // 如果发生错误，则假定不支持该功能
  }

  return false;
}


asyn_c function detectDeviceFeatures(device) {
  // 示例 1：检查特定的 LED 控制功能（假设的报告 ID）
  const ledControlReportId = 0x01;
  const ledControlResponseValue = 0x01; // 指示支持 LED 的期望值。
  const hasLedControl = await checkFeatureSupport(device, ledControlReportId, ledControlResponseValue);

  if (hasLedControl) {
    console.log("Device supports LED control!");
  } else {
    console.log("Device does not support LED control.");
  }

  // 示例 2：检查特定的传感器功能（假设的报告 ID）
  const sensorReportId = 0x02;
  const sensorResponseValue = 0x01; // 指示支持传感器的期望值。
  const hasSensor = await checkFeatureSupport(device, sensorReportId, sensorResponseValue);

  if (hasSensor) {
    console.log("Device has a sensor!");
  } else {
    console.log("Device does not have a sensor.");
  }
}

挑战：

• 需要特定于设备的知识：您需要知道要检测的功能的特定报告 ID 和预期响应。这些信息通常可以在设备的文档或规格中找到。
• 错误处理：您需要处理潜在的错误，例如设备不响应或返回意外值。
• 假设设备一致性：依赖于这样的假设：在同一类型的不同设备中，特定的报告 ID 将始终对应于相同的功能。

适用场景：

• 当您可以访问设备的文档或规格，其中提供了必要的报告 ID 和预期响应时。
• 当您需要检测标准 HID 用法未涵盖的特定功能时。

3. 供应商定义的用法页和用法：识别自定义功能

HID 规范允许供应商定义自定义的用法页和用法来表示供应商特定的功能。一个用法页是相关用法的命名空间，而一个用法则定义了该页面内的特定功能或属性。通过查询这些供应商定义的值，您可以识别自定义功能的存在。

示例：

此示例演示了概念。实际实现可能需要读取报告描述符以确定可用的用法。

// 这是一个概念性说明。WebHID 并不直接
// 暴露在没有进一步描述符分析的情况下查询用法页/用法的方法。

asyn_c function checkVendorDefinedFeature(device, vendorId, featureUsagePage, featureUsage) {
  // 简化逻辑 - 如果未来的 WebHID 版本提供，请替换为实际方法
  if (device.vendorId === vendorId) {
    // 假设内部可以进行用法检查
    // if (device.hasUsage(featureUsagePage, featureUsage)) { // 假设的函数
    //   console.log("Device supports vendor-defined feature!");
    //   return true;
    // }

    console.log("Cannot directly verify the device supports Vendor-defined feature. Consider other methods.");

  } else {
    console.log("Device does not match the expected vendor ID.");
  }

  return false;
}


asyn_c function detectVendorFeatures(device) {
  // 示例：检查由供应商 XYZ 定义的自定义功能（假设）
  const vendorId = 0x1234; // 假设的供应商 ID
  const featureUsagePage = 0xF001; // 假设的供应商定义用法页
  const featureUsage = 0x0001; // 该功能的假设用法

  const hasVendorFeature = await checkVendorDefinedFeature(device, vendorId, featureUsagePage, featureUsage);

  // 使用功能报告的替代方法示例。实际使用需要报告描述符分析。
  if (hasVendorFeature) {
    console.log("Device supports Vendor XYZ's custom feature!");
  } else {
    console.log("Device does not support Vendor XYZ's custom feature.");
  }
}

挑战：

• 需要供应商文档：您需要访问供应商的文档来理解其自定义用法页和用法的含义。
• 缺乏标准化：供应商定义的功能没有标准化，这使得创建通用的功能检测代码变得困难。
• 有限的 WebHID 支持：当前的 WebHID 实现可能无法在没有更高级的报告描述符分析的情况下直接暴露查询用法页和用法的方法。

适用场景：

• 当您正在使用特定供应商的硬件并可以访问其文档时。
• 当您需要检测标准 HID 用法未涵盖的自定义功能时。

4. 预定义功能集或数据库：简化设备识别

一种实用的功能检测方法是根据供应商 ID、产品 ID 或其他识别特征维护一个已知设备功能的数据库。这允许您的 Web 应用程序快速识别常见设备并应用预定义的配置或功能集。

示例：

const deviceDatabase = {
  "046d:c52b": { // 罗技 G502 游戏鼠标 (供应商 ID:产品 ID)
    features: {
      dpiAdjustment: true,
      programmableButtons: 11,
      rgbLighting: true
    }
  },
  "04f3:0c4b": { // Elgato Stream Deck (供应商 ID:产品 ID)
    features: {
      lcdButtons: true,
      customIcons: true,
      hotkeys: true
    }
  }
  // ... 更多设备定义 ...
};


asyn_c function detectDeviceFeaturesFromDatabase(device) {
  const deviceId = `${device.vendorId.toString(16)}:${device.productId.toString(16)}`;

  if (deviceDatabase[deviceId]) {
    const features = deviceDatabase[deviceId].features;
    console.log("Device found in database!");
    console.log("Features:", features);
    return features;
  } else {
    console.log("Device not found in database.");
    return null; // 未识别的设备
  }
}

挑战：

• 数据库维护：使数据库与新设备和功能保持同步需要持续的努力。
• 覆盖范围有限：数据库可能不包含所有可能的 HID 设备的信息，特别是那些不常见或定制的硬件。
• 可能存在不准确性：数据库中的设备信息可能不完整或不准确，导致功能检测错误。

适用场景：

• 当您需要支持各种常见的 HID 设备时。
• 当您希望提供一种快速简便的方式来配置设备，而无需用户手动设置功能时。
• 作为其他功能检测方法失败时的后备机制。

WebHID 功能检测的最佳实践

• 优先考虑用户隐私：始终明确地向用户请求设备访问权限，并清楚地解释为什么您需要访问他们的 HID 设备。
• 提供后备机制：如果功能检测失败，提供一种方式让用户手动配置他们的设备或从支持的功能列表中选择。
• 优雅地处理错误：实现健壮的错误处理，以防止意外行为或崩溃。
• 使用异步操作：WebHID 操作是异步的，因此请确保使用 async 和 await 以避免阻塞主线程。
• 优化性能：最小化功能检测请求的数量，以提高性能并减少电池消耗。
• 考虑外部库：探索使用为 WebHID 功能检测提供更高级别抽象的外部库或模块。
• 充分测试：使用各种 HID 设备测试您的代码，以确保兼容性和准确性。考虑使用自动化测试框架来简化测试过程。

真实世界示例和用例

• 游戏：根据检测到的按钮、轴和传感器动态调整游戏手柄布局。
• 辅助功能：为辅助设备（如替代键盘或指点设备）调整用户界面。
• 工业控制：与制造业、机器人技术和其他工业应用中使用的自定义传感器和执行器进行交互。例如，一个 Web 应用程序可以检测通过 USB-HID 连接的特定温度传感器或压力表的存在。
• 教育：构建利用专用硬件（如电子显微镜或数据采集系统）的交互式学习工具。
• 医疗保健：连接到医疗设备（如脉搏血氧仪或血压计）以进行远程患者监护。
• 数字艺术：支持具有压力感应和倾斜检测功能的各种绘图板和手写笔。一个全球性的例子是支持世界各地艺术家使用的 Wacom 数位板，正确解释压力级别和按钮配置。

结论

功能检测是使用 WebHID 构建健壮且用户友好的 Web 应用程序的关键方面。通过理解 HID 报告、描述符和各种检测方法的概念，您可以释放这个强大 API 的全部潜力。尽管存在挑战，特别是在直接访问描述符方面，但结合不同方法和利用外部资源可以带来更有效和适应性更强的解决方案。随着 WebHID 的不断发展，我们可以期待在功能检测能力方面看到进一步的改进，从而更容易地创建能够与各种硬件设备无缝交互的引人入胜的 Web 体验。

请记住优先考虑用户隐私，优雅地处理错误，并进行彻底测试，以确保为您的用户提供积极可靠的体验。通过掌握 WebHID 功能检测的艺术，您可以构建真正创新和引人入胜的 Web 应用程序，弥合数字世界和物理世界之间的鸿沟。